<proc_def_begin> : Begin Of Procedure
This command defines begin of procedure.
Procedure is a piece of macro code that can be called using
<proc_call> command from other places
within
the macro. Procedure can contain any number of parameters.
Procedures do not return any value but it is possible to pass results out of the
procedure using reference parameters. Reference parameter, instead
of containing value, contains name of the variable it references to. To
tell the procedure that a parameter is reference to a variable, this syntax is
used: &parParam3&. Such syntax means, that parParam3 (parParam3 is just
example) holds the name of variable passed as a parameter in <proc_call> command. Example: Let's have <proc_def_begin>(P1,
"parParam1","&parParam2&") and let's have procedure call <proc_call>(P1, "555", "vResult").
Now, any modification of Param2 (that
is is done within the P1 procedure) is actually done on vResult variable
since the parParam2 is not a variable that holds any value but it just
references to vResult variable. It is not allowed to have
reference variable and other (global) variable of the same name. This
means, for example, that if there is "&vInput&" reference parameter then it is
not possible to have other variable named "vInput"!
When getting actual value of the referenced variable, it is always necessary
to enclose it to % since parParam2 gives you name of the variable it
references to while %parParam2% gives the value stored.
If a procedure parameter starts with "par" prefix
(for example, "parInputText") then the parameter is local only within the
procedure and cannot be accessed out of the procedure. In addition, if a
variable defined within a procedure starts with "lpv" (local
procedure variable) prefix (for example, "lpvTemporaryVariable")
then the variable is known and can be accessed only within the procedure.
See more about variables and language rules
here.
It is not allowed to define procedure within other procedure (embedded <proc_def_begin>).
The procedure definition must be ended by <proc_def_end> command.
See more in the example below.
Syntax:
<proc_def_begin>(ProcedureName,
"parParam1", "parParam2", ....,
parParamN")
ProcedureName
Unique name of the procedure. The name is used as a parameter in
<proc_call>
command to identify what procedure to call.
parParam1, parParam2,...,parParamN
Any number of parameters.
Example:
<#>
This example shows how to use procedures
<cmds>
<proc_def_begin>(AddQuotes,"parStringInput", "&parStringOutput&")
<varset>("parStringOutput=%_vQuoteChar%%parStringInput%%_vQuoteChar%","")
<proc_def_end>
<proc_def_begin>(ConvertToUpper,"parStringInput","&parStringOutput&")
<var_oper>(parStringOutput,"%parStringInput%",STR_UPPER,"2","", "0")
<proc_def_end>
<varset>("vMyText=","Insert text to modify:")
<if_str>("_vCanceled==1")<exitmacro><endif>
<proc_call>(ConvertToUpper,"%vMyText%",
"vMyText" )
<proc_call>(AddQuotes,"%vMyText%", "vMyText" )
<msg>(-100,-100,"%vMyText%","Message",1)